docs(adr): reconcile proposed governance policies#457
Merged
Merged
Conversation
Member
Author
|
@copilot resolve the merge conflicts in this pull request |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reconciles the wording of proposed governance ADRs (0008–0010) with the audited, live GitHub branch behavior and current rollout gaps, without changing any operational workflows or settings.
Changes:
- Clarifies the distinction between GitHub default branches (
main) and development/integration branches (next) in ADR 0008, and documents outstanding catalog drift as a separate follow-up. - Reframes ADR 0009 as target CI policy with explicit non-claims about current enforcement/required-checks and updates ownership references to ADR 0012.
- Updates ADR 0010’s intake, escalation, disclosure, and verification language to match supported GitHub security advisory behavior and explicitly flags unverified admin controls.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| decisions/0008-branching-model.md | Updates branching-model terminology and tables to reflect audited default vs development branch reality and defers private catalog fixes. |
| decisions/0009-testing-ci-strategy.md | Recasts CI strategy as target policy with tracked rollout gaps; updates dependency ownership references and adds pre-acceptance decision checklist. |
| decisions/0010-security-incident-response.md | Aligns security incident intake/escalation/disclosure guidance with GitHub advisory capabilities and adds explicit admin-verification caveats and acceptance prerequisites. |
Contributor
Resolved. I merged |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
decisions/0008-branching-model.md:24
- Grammar: “is still drifted” is unidiomatic English and reads like a typo. Consider rephrasing to “is still out of date” (or “is still drifting”) to clearly convey that the catalog doesn’t match current reality.
The private meta-workspace catalog (`workspace/repos.yml`) is still drifted. Its
0008: "is still drifted" -> "is still out of date" per Copilot review. 0009: the copilot-swe-agent conflict resolution against origin/main (59753e0) took this branch's reworded disallowed-trailer bullet and silently dropped main's independently-added evidence (the 86-repository sweep finding no live DISALLOWED_TRAILER_PATTERN workflow, and the zi next-branch exception). Restored that evidence inside the target-policy framing instead of picking one side over the other.
Copilot review: AGENTS.md is a high-level summary, not the source of the specific conventions this bullet lists; cite the instructions file and ADR-0005 that actually define them. Also flag that testing.instructions.md currently states enforcement in the present tense, which is target-state language this ADR should not let stand uncontextualized.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
decisions/0009-testing-ci-strategy.md:40
- This baseline item is written as present-tense fact, which can be misread as asserting the checks are already running everywhere. If this ADR is meant to describe target CI scope, consider stating it as a target requirement.
- Zsh sources pass `zsh -n` (syntax) and `zcompile` (compile) checks.
Per the decision packet in #454 (comment 5013565657), decider ss-o, 2026-07-25: ADR-0008: ACCEPTED (8A). The src/zd semantic-tag publication triggers are recorded as accepted class-1 compatibility paths rather than an open question. Removed the now-resolved 'Decision review required' section and converted conditional 'if accepted' wording to direct statements throughout. ADR-0009: ACCEPTED as target policy (9A). Wove in the 9Z1 packaged-zsh release-gate definition, the 9U1 zunit release-gate requirement, and the 9R1 per-repository verification methodology. Reframed the 'Baseline (all repos)' bullets with a single target-policy lead-in instead of one hedged bullet among unhedged ones, closing the framing gap Copilot flagged after the 9A/9B question was open. Removed the now-resolved 'Decision review required' section. ADR-0010: stays PROPOSED (10D1). Recorded the 10S1 confirmation of the acknowledgement/triage/remediation targets directly in the SLA and severity sections and marked item 1 of the review checklist done, while items 2 (backup contact) and 3 (administrative verification) remain open and continue to block acceptance.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
Comments suppressed due to low confidence (1)
decisions/0010-security-incident-response.md:129
- This bullet references
SECURITY.md, but the file in this repo is.github/SECURITY.md. Keeping the path consistent avoids implying a root-level policy file exists.
- `SECURITY.md` remains the reporter-facing entry point and would be reconciled
Copilot review: the repo's security policy file is .github/SECURITY.md; three references in this ADR were missing the .github/ prefix. The Context section and References already had it right.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
decisions/0009-testing-ci-strategy.md:51
- This baseline bullet reads as both a target requirement ("are enforced in CI") and a statement that the controls are not currently enforced org-wide. Since this ADR is now ACCEPTED, it would be clearer to phrase this as target policy with current rollout tracked elsewhere (issue #454), and avoid embedding detailed sweep evidence here (which contradicts the earlier statement that rollout evidence is tracked in #454 rather than copied into the ADR).
- Conventional Commits (ADR-0003), PR-title validation, and the
disallowed-trailer rule are enforced in CI. None of these is a live org-wide
gate today: a sweep of the default branches of all 86 active, non-fork,
non-archived repositories found no workflow that runs the
`DISALLOWED_TRAILER_PATTERN` check or validates commit messages. Non-default
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PROPOSEDWhy
The 2026-07-18 audit in #454 found factual drift between the proposed ADR wording, live repository behavior, and supporting policy files. This PR makes the public decision records accurate enough for an explicit maintainer disposition without inferring acceptance.
This is deliberately ADR-only. It does not change workflows, security settings,
.github/SECURITY.mditself, the incident-response runbook, testing instructions, or the private meta-workspace catalog/root guidance. Owning-repository rollout issues remain deferred until the maintainer decides which target policies become authoritative.Maintainer disposition (2026-07-25)
Decider ss-o, replying to the decision packet in #454 comment 5013565657 with:
src/zdsemantic-tag triggers are recorded as accepted class-1 compatibility publication paths rather than an open question.zshrelease gate: metadata/manifest validation plus a clean disposable install and startup/version smoke test on the exact tag commit), 9U1 (zunit's release workflow must run its native suite on the exact tag commit), and 9R1 (required checks/SAST/release gates are verified repository by repository through owning issues, never assumed from a workflow file's presence) woven into the ADR text.PROPOSED(10D1). 10S1's acknowledgement/triage/remediation targets are confirmed and now recorded directly in the SLA and severity sections. Items 2 (named, permission-verified backup incident contact) and 3 (administrative verification of private reporting/notifications/release immutability) remain open and continue to block full acceptance.This resolves all 6 items in "Maintainer decisions requested" below (kept as the historical record of what was asked). It supersedes the original "keep all three ADRs
PROPOSEDwithDeciders: TBD" framing in this PR's Summary and Verification sections for ADRs 0008 and 0009 specifically; ADR 0010's disposition matches the original framing.Maintainer decisions requested
mainwhilenextis the development/integration branch for the five listed repositories.srcandzdsemantic-tag publication triggers are accepted exceptions.zshfunctional suite, the zunit release gate, and actual required checks.Verification
First pass (initial reconciliation commits):
git diff --check: passedPROPOSEDwithDeciders: TBDat that pointSecond pass (Copilot review responses, merge-conflict resolution with
main, and the 2026-07-25 disposition commit):git diff --check: passedmain-merge conflict resolution indecisions/0009-testing-ci-strategy.mdagainst both parents; restored evidence one side had droppedSECURITY.md->.github/SECURITY.mdpath error in ADR-0010 (repo's actual file is under.github/)Tracking
The owning issue remains open for the two ADR-0010 rollout gaps (backup contact, administrative verification) and the separate private catalog reconciliation.